<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="module-rlcompleter.html" />
<link rel="prev" href="module-mmap.html" />
<link rel="parent" href="someos.html" />
<link rel="next" href="readline-example.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>15.7 readline -- GNU readline interface</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="15.6 mmap  "
  href="module-mmap.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="15. optional Operating System"
  href="someos.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="15.7.1 Example"
  href="readline-example.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-mmap.html">15.6 mmap  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="someos.html">15. Optional Operating System</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="readline-example.html">15.7.1 Example</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h1><a name="SECTION0017700000000000000000">
15.7 <tt class="module">readline</tt> --
         GNU readline interface</a>
</h1>

<p>
<a name="module-readline"></a>  
<p class="availability">Availability: <span
 class="platform">Unix</span>.</p>

<p>
The <tt class="module">readline</tt> module defines a number of functions to
facilitate completion and reading/writing of history files from the
Python interpreter.  This module can be used directly or via the
<tt class="module"><a href="module-rlcompleter.html">rlcompleter</a></tt> module.  Settings made using 
this module affect the behaviour of both the interpreter's interactive prompt 
and the prompts offered by the <tt class="function">raw_input()</tt> and <tt class="function">input()</tt>
built-in functions.

<p>
The <tt class="module">readline</tt> module defines the following functions:

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3485' xml:id='l2h-3485' class="function">parse_and_bind</tt></b>(</nobr></td>
  <td><var>string</var>)</td></tr></table></dt>
<dd>
Parse and execute single line of a readline init file.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3486' xml:id='l2h-3486' class="function">get_line_buffer</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the current contents of the line buffer.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3487' xml:id='l2h-3487' class="function">insert_text</tt></b>(</nobr></td>
  <td><var>string</var>)</td></tr></table></dt>
<dd>
Insert text into the command line.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3488' xml:id='l2h-3488' class="function">read_init_file</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>filename</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Parse a readline initialization file.
The default filename is the last filename used.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3489' xml:id='l2h-3489' class="function">read_history_file</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>filename</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Load a readline history file.
The default filename is <span class="file">~/.history</span>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3490' xml:id='l2h-3490' class="function">write_history_file</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>filename</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Save a readline history file.
The default filename is <span class="file">~/.history</span>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3491' xml:id='l2h-3491' class="function">clear_history</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Clear the current history.  (Note: this function is not available if
the installed version of GNU readline doesn't support it.)

<span class="versionnote">New in version 2.4.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3492' xml:id='l2h-3492' class="function">get_history_length</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the desired length of the history file.  Negative values imply
unlimited history file size.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3493' xml:id='l2h-3493' class="function">set_history_length</tt></b>(</nobr></td>
  <td><var>length</var>)</td></tr></table></dt>
<dd>
Set the number of lines to save in the history file.
<tt class="function">write_history_file()</tt> uses this value to truncate the
history file when saving.  Negative values imply unlimited history
file size.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3494' xml:id='l2h-3494' class="function">get_current_history_length</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the number of lines currently in the history.  (This is different
from <tt class="function">get_history_length()</tt>, which returns the maximum number of
lines that will be written to a history file.)  
<span class="versionnote">New in version 2.3.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3495' xml:id='l2h-3495' class="function">get_history_item</tt></b>(</nobr></td>
  <td><var>index</var>)</td></tr></table></dt>
<dd>
Return the current contents of history item at <var>index</var>.

<span class="versionnote">New in version 2.3.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3496' xml:id='l2h-3496' class="function">remove_history_item</tt></b>(</nobr></td>
  <td><var>pos</var>)</td></tr></table></dt>
<dd>
Remove history item specified by its position from the history.

<span class="versionnote">New in version 2.4.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3497' xml:id='l2h-3497' class="function">replace_history_item</tt></b>(</nobr></td>
  <td><var>pos, line</var>)</td></tr></table></dt>
<dd>
Replace history item specified by its position with the given line.

<span class="versionnote">New in version 2.4.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3498' xml:id='l2h-3498' class="function">redisplay</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Change what's displayed on the screen to reflect the current contents
of the line buffer.  
<span class="versionnote">New in version 2.3.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3499' xml:id='l2h-3499' class="function">set_startup_hook</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>function</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Set or remove the startup_hook function.  If <var>function</var> is specified,
it will be used as the new startup_hook function; if omitted or
<code>None</code>, any hook function already installed is removed.  The
startup_hook function is called with no arguments just
before readline prints the first prompt.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3500' xml:id='l2h-3500' class="function">set_pre_input_hook</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>function</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Set or remove the pre_input_hook function.  If <var>function</var> is specified,
it will be used as the new pre_input_hook function; if omitted or
<code>None</code>, any hook function already installed is removed.  The
pre_input_hook function is called with no arguments after the first prompt
has been printed and just before readline starts reading input characters.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3501' xml:id='l2h-3501' class="function">set_completer</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>function</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Set or remove the completer function.  If <var>function</var> is specified,
it will be used as the new completer function; if omitted or
<code>None</code>, any completer function already installed is removed.  The
completer function is called as <code><var>function</var>(<var>text</var>,
<var>state</var>)</code>, for <var>state</var> in <code>0</code>, <code>1</code>, <code>2</code>, ...,
until it returns a non-string value.  It should return the next
possible completion starting with <var>text</var>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3502' xml:id='l2h-3502' class="function">get_completer</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Get the completer function, or <code>None</code> if no completer function
has been set.  
<span class="versionnote">New in version 2.3.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3503' xml:id='l2h-3503' class="function">get_begidx</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Get the beginning index of the readline tab-completion scope.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3504' xml:id='l2h-3504' class="function">get_endidx</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Get the ending index of the readline tab-completion scope.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3505' xml:id='l2h-3505' class="function">set_completer_delims</tt></b>(</nobr></td>
  <td><var>string</var>)</td></tr></table></dt>
<dd>
Set the readline word delimiters for tab-completion.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3506' xml:id='l2h-3506' class="function">get_completer_delims</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Get the readline word delimiters for tab-completion.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3507' xml:id='l2h-3507' class="function">add_history</tt></b>(</nobr></td>
  <td><var>line</var>)</td></tr></table></dt>
<dd>
Append a line to the history buffer, as if it was the last line typed.
</dl>

<p>
<div class="seealso">
  <p class="heading">See Also:</p>

  <dl compact="compact" class="seemodule">
    <dt>Module <b><tt class="module"><a href="module-rlcompleter.html">rlcompleter</a></tt>:</b>
    <dd>Completion of Python identifiers at the
                          interactive prompt.
  </dl>
</div>

<p>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<a name="CHILD_LINKS"><strong>Subsections</strong></a>

<ul class="ChildLinks">
<li><a href="readline-example.html">15.7.1 Example</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="15.6 mmap  "
  href="module-mmap.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="15. optional Operating System"
  href="someos.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="15.7.1 Example"
  href="readline-example.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-mmap.html">15.6 mmap  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="someos.html">15. Optional Operating System</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="readline-example.html">15.7.1 Example</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
